<html>

<head>
<title>Ocave documentation</title>
</head>

<body>
<h1>Ocave documentation</h1>

<h2>Data types</h2>

<p> For Ocave, ParameterWeaver supports the following data types:
<ol>
  <li> <tt>double</tt> </li>
  <li> <tt>logical</tt> </li>
  <li> <tt>string</tt> </li>
</ol>
</p>

<h2>Example Octave script</h2>
<p> Suppose we want to pass command line parameters to the following Octave script:
<pre>
if (size(out) &gt; 0)
    fid = fopen(out, "w");
else
    fid = stdout;
end
if (verbose)
	fprintf(fid, "# n = %.16f\n", prefix, params.n);
	fprintf(fid, "# alpha = %.16f\n", alpha);
	fprintf(fid, "# out = '%s'\n", out);
	fprintf(fid, "# verbose = %1d\n", verbose);
end
for i = 1:n
    fprintf(fid, "%d\t%f\n", i, i*alpha);
end
if (fid != stdout)
    fclose(fid);
end

</pre>
We would like to set the number of iterations <tt>n</tt>, the factor <tt>alpha</tt>, the name of the file to write the output to <tt>out</tt> and the verbosity <tt>verbose</tt> at runtime, i.e., without modifying the source code of this script. </p>
<p> Moreover, the code to print the values of the variables is error prone, if we later add or remove a parameter, this part of the code has to be updated as well. </p>
<p> Defining the command line parameters in a parameter definition file to automatlically generate the necessary code simplifies matters considerably. </p>

<h2>Example parameter definition file</h2>
The following file defines four command line parameters named <tt>n</tt>, <tt>alpha</tt>,  <tt>out</tt> and <tt>verbose</tt>.  They are to be interpreted as <tt>double</tt>, <tt>double</tt>, string and <tt>logical</tt> respectively, and if no values are passed via the command line, they will have the default values <tt>10</tt>, <tt>0.19</tt>, <tt>output.txt</tt> and false respectively.  Note that a string default value is quoted, just as it would be in Octave code.  In this case, the columns in the file are separated by tab characters.  The following is the contents of the parameter definition file <tt>param_defs.txt</tt>:
<pre>
double	n	10
double	alpha	0.19
string	out	'output.txt'
logical	verbose	F
</pre>
This parameter definition file can be created in a text editor such as the one used to write Octave scripts, or from a Microsoft Excel worksheet by saving the latter as a CSV file. </p>
<p> As mentioned above, logical values are also supported, however, the semantics is slightly different from other data types.  The default value of a logical variable is always false, regardless of what is specified in the parameter definition file.  As opposed to parameters of other types, a logical parameter acts like a flag, i.e., it is a command line options that doesn't take a value.  Its absence is interpreted as false, its presence as true. </p>

<h2>Generating code</h2>
<p> Generating the code fragments is now very easy.  If appropriate, load the module (VIC3):
<pre>
$ module load parameterweaver
</pre>
Next, we generate the code based on the parameter definition file:
<pre>
$ weave -l octave -d param_defs.txt
</pre>
<p> Three code fragments are generated, each in its own file, i.e., <tt>init_cl.m</tt>, <tt>parse_cl.m</tt>, and <tt>dump_cl.m</tt>.r</tt>.
<ol>
  <li> Initialization: the default values of the command line parameters are assigned to global variables with the names as specified in the parameter definition file. </li>
  <li> Parsing: the options passed to the program via the command line are assigned to the appropriate variables.  Moreover, an array containing the remaining command line arguments is returned as the second value from <tt>parse_cl</tt>. </li>
  <li> Dumper: a function is defined that takes two arguments: a file connector and a prefix.  This function writes the values of the command line parameters to the file connector, each on a separate line, preceeded by the specified prefix. </li>
</ol>
</p>

<h2>Using the code fragments</h2>
<p> The generated functions can be used by simply calling them from the main script.
The code for the script is thus modified as follows:
<pre>
params = init_cl();
params = parse_cl(params);
if (size(params.out) &gt; 0)
    fid = fopen(params.out, "w");
else
    fid = stdout;
end
if (params.verbose)
    dump_cl(stdout, "# ", params);
end
for i = 1:params.n
    fprintf(fid, "%d\t%f\n", i, i*params.alpha);
end
if (fid != stdout)
    fclose(fid);
end

</pre>
Note that in this example, additional command line parameters are simply ignored.  As mentioned before, they are can be obtained as the second return value from the call to <tt>parse_cl</tt>. </p>

</body>

</html>
